These macros have the same function as their `bfd_get_x' brethren,
except that they are used for removing information for the header
records of object files. Believe it or not, some object files keep
their header records in big endian order and their data in little
endian order.
/* Byte swapping macros for file header data. */
#define bfd_h_put_8(abfd, val, ptr) \
bfd_put_8 (abfd, val, ptr)
#define bfd_h_put_signed_8(abfd, val, ptr) \
bfd_put_8 (abfd, val, ptr)
#define bfd_h_get_8(abfd, ptr) \
bfd_get_8 (abfd, ptr)
#define bfd_h_get_signed_8(abfd, ptr) \
bfd_get_signed_8 (abfd, ptr)
#define bfd_h_put_16(abfd, val, ptr) \
BFD_SEND (abfd, bfd_h_putx16, (val, ptr))
#define bfd_h_put_signed_16 \
bfd_h_put_16
#define bfd_h_get_16(abfd, ptr) \
BFD_SEND (abfd, bfd_h_getx16, (ptr))
#define bfd_h_get_signed_16(abfd, ptr) \
BFD_SEND (abfd, bfd_h_getx_signed_16, (ptr))
#define bfd_h_put_32(abfd, val, ptr) \
BFD_SEND (abfd, bfd_h_putx32, (val, ptr))
#define bfd_h_put_signed_32 \
bfd_h_put_32
#define bfd_h_get_32(abfd, ptr) \
BFD_SEND (abfd, bfd_h_getx32, (ptr))
#define bfd_h_get_signed_32(abfd, ptr) \
BFD_SEND (abfd, bfd_h_getx_signed_32, (ptr))
#define bfd_h_put_64(abfd, val, ptr) \
BFD_SEND (abfd, bfd_h_putx64, (val, ptr))
#define bfd_h_put_signed_64 \
bfd_h_put_64
#define bfd_h_get_64(abfd, ptr) \
BFD_SEND (abfd, bfd_h_getx64, (ptr))
#define bfd_h_get_signed_64(abfd, ptr) \
BFD_SEND (abfd, bfd_h_getx_signed_64, (ptr))
/* Aliases for the above, which should eventually go away. */
#define H_PUT_64 bfd_h_put_64
#define H_PUT_32 bfd_h_put_32
#define H_PUT_16 bfd_h_put_16
#define H_PUT_8 bfd_h_put_8
#define H_PUT_S64 bfd_h_put_signed_64
#define H_PUT_S32 bfd_h_put_signed_32
#define H_PUT_S16 bfd_h_put_signed_16
#define H_PUT_S8 bfd_h_put_signed_8
#define H_GET_64 bfd_h_get_64
#define H_GET_32 bfd_h_get_32
#define H_GET_16 bfd_h_get_16
#define H_GET_8 bfd_h_get_8
#define H_GET_S64 bfd_h_get_signed_64
#define H_GET_S32 bfd_h_get_signed_32
#define H_GET_S16 bfd_h_get_signed_16
#define H_GET_S8 bfd_h_get_signed_8
2.16.0.5 `bfd_log2'
...................
*Synopsis*
unsigned int bfd_log2 (bfd_vma x);
*Description*
Return the log base 2 of the value supplied, rounded up. E.g., an X of
1025 returns 11. A X of 0 returns 0.
File: bfd.info, Node: File Caching, Next: Linker Functions, Prev: Internal, Up: BFD front end
2.17 File caching
=================
The file caching mechanism is embedded within BFD and allows the
application to open as many BFDs as it wants without regard to the
underlying operating system's file descriptor limit (often as low as 20
open files). The module in `cache.c' maintains a least recently used
list of `BFD_CACHE_MAX_OPEN' files, and exports the name
`bfd_cache_lookup', which runs around and makes sure that the required
BFD is open. If not, then it chooses a file to close, closes it and
opens the one wanted, returning its file handle.
2.17.0.1 `BFD_CACHE_MAX_OPEN macro'
...................................
*Description*
The maximum number of files which the cache will keep open at one time.
#define BFD_CACHE_MAX_OPEN 10
2.17.0.2 `bfd_last_cache'
.........................
*Synopsis*
extern bfd *bfd_last_cache;
*Description*
Zero, or a pointer to the topmost BFD on the chain. This is used by
the `bfd_cache_lookup' macro in `libbfd.h' to determine when it can
avoid a function call.
2.17.0.3 `bfd_cache_lookup'
...........................
*Description*
Check to see if the required BFD is the same as the last one looked up.
If so, then it can use the stream in the BFD with impunity, since it
can't have changed since the last lookup; otherwise, it has to perform
the complicated lookup function.
#define bfd_cache_lookup(x) \
((x) == bfd_last_cache ? \
(FILE *) (bfd_last_cache->iostream): \
bfd_cache_lookup_worker (x))
2.17.0.4 `bfd_cache_init'
.........................
*Synopsis*
bfd_boolean bfd_cache_init (bfd *abfd);
*Description*
Add a newly opened BFD to the cache.
2.17.0.5 `bfd_cache_close'
..........................
*Synopsis*
bfd_boolean bfd_cache_close (bfd *abfd);
*Description*
Remove the BFD ABFD from the cache. If the attached file is open, then
close it too.
*Returns*
`FALSE' is returned if closing the file fails, `TRUE' is returned if
all is well.
2.17.0.6 `bfd_cache_close_all'
..............................
*Synopsis*
bfd_boolean bfd_cache_close_all (void);
*Description*
Remove all BFDs from the cache. If the attached file is open, then
close it too.
*Returns*
`FALSE' is returned if closing one of the file fails, `TRUE' is
returned if all is well.
2.17.0.7 `bfd_open_file'
........................
*Synopsis*
FILE* bfd_open_file (bfd *abfd);
*Description*
Call the OS to open a file for ABFD. Return the `FILE *' (possibly
`NULL') that results from this operation. Set up the BFD so that
future accesses know the file is open. If the `FILE *' returned is
`NULL', then it won't have been put in the cache, so it won't have to
be removed from it.
2.17.0.8 `bfd_cache_lookup_worker'
..................................
*Synopsis*
FILE *bfd_cache_lookup_worker (bfd *abfd);
*Description*
Called when the macro `bfd_cache_lookup' fails to find a quick answer.
Find a file descriptor for ABFD. If necessary, it open it. If there
are already more than `BFD_CACHE_MAX_OPEN' files open, it tries to
close one first, to avoid running out of file descriptors. It will
abort rather than returning NULL if it is unable to (re)open the ABFD.
File: bfd.info, Node: Linker Functions, Next: Hash Tables, Prev: File Caching, Up: BFD front end
2.18 Linker Functions
=====================
The linker uses three special entry points in the BFD target vector.
It is not necessary to write special routines for these entry points
when creating a new BFD back end, since generic versions are provided.
However, writing them can speed up linking and make it use
significantly less runtime memory.
The first routine creates a hash table used by the other routines.
The second routine adds the symbols from an object file to the hash
table. The third routine takes all the object files and links them
together to create the output file. These routines are designed so
that the linker proper does not need to know anything about the symbols
in the object files that it is linking. The linker merely arranges the
sections as directed by the linker script and lets BFD handle the
details of symbols and relocs.
The second routine and third routines are passed a pointer to a
`struct bfd_link_info' structure (defined in `bfdlink.h') which holds
information relevant to the link, including the linker hash table
(which was created by the first routine) and a set of callback
functions to the linker proper.
The generic linker routines are in `linker.c', and use the header
file `genlink.h'. As of this writing, the only back ends which have
implemented versions of these routines are a.out (in `aoutx.h') and
ECOFF (in `ecoff.c'). The a.out routines are used as examples
throughout this section.
* Menu:
* Creating a Linker Hash Table::
* Adding Symbols to the Hash Table::
* Performing the Final Link::
File: bfd.info, Node: Creating a Linker Hash Table, Next: Adding Symbols to the Hash Table, Prev: Linker Functions, Up: Linker Functions
2.18.1 Creating a linker hash table
-----------------------------------
The linker routines must create a hash table, which must be derived
from `struct bfd_link_hash_table' described in `bfdlink.c'. *Note Hash
Tables::, for information on how to create a derived hash table. This
entry point is called using the target vector of the linker output file.
The `_bfd_link_hash_table_create' entry point must allocate and
initialize an instance of the desired hash table. If the back end does
not require any additional information to be stored with the entries in
the hash table, the entry point may simply create a `struct
bfd_link_hash_table'. Most likely, however, some additional
information will be needed.
For example, with each entry in the hash table the a.out linker
keeps the index the symbol has in the final output file (this index
number is used so that when doing a relocatable link the symbol index
used in the output file can be quickly filled in when copying over a
reloc). The a.out linker code defines the required structures and
functions for a hash table derived from `struct bfd_link_hash_table'.
The a.out linker hash table is created by the function
`NAME(aout,link_hash_table_create)'; it simply allocates space for the
hash table, initializes it, and returns a pointer to it.
When writing the linker routines for a new back end, you will
generally not know exactly which fields will be required until you have
finished. You should simply create a new hash table which defines no
additional fields, and then simply add fields as they become necessary.
File: bfd.info, Node: Adding Symbols to the Hash Table, Next: Performing the Final Link, Prev: Creating a Linker Hash Table, Up: Linker Functions
2.18.2 Adding symbols to the hash table
---------------------------------------
The linker proper will call the `_bfd_link_add_symbols' entry point for
each object file or archive which is to be linked (typically these are
the files named on the command line, but some may also come from the
linker script). The entry point is responsible for examining the file.
For an object file, BFD must add any relevant symbol information to
the hash table. For an archive, BFD must determine which elements of
the archive should be used and adding them to the link.
The a.out version of this entry point is
`NAME(aout,link_add_symbols)'.
* Menu:
* Differing file formats::
* Adding symbols from an object file::
* Adding symbols from an archive::
File: bfd.info, Node: Differing file formats, Next: Adding symbols from an object file, Prev: Adding Symbols to the Hash Table, Up: Adding Symbols to the Hash Table
2.18.2.1 Differing file formats
...............................
Normally all the files involved in a link will be of the same format,
but it is also possible to link together different format object files,
and the back end must support that. The `_bfd_link_add_symbols' entry
point is called via the target vector of the file to be added. This
has an important consequence: the function may not assume that the hash
table is the type created by the corresponding
`_bfd_link_hash_table_create' vector. All the `_bfd_link_add_symbols'
function can assume about the hash table is that it is derived from
`struct bfd_link_hash_table'.
Sometimes the `_bfd_link_add_symbols' function must store some
information in the hash table entry to be used by the `_bfd_final_link'
function. In such a case the `creator' field of the hash table must be
checked to make sure that the hash table was created by an object file
of the same format.
The `_bfd_final_link' routine must be prepared to handle a hash
entry without any extra information added by the
`_bfd_link_add_symbols' function. A hash entry without extra
information will also occur when the linker script directs the linker
to create a symbol. Note that, regardless of how a hash table entry is
added, all the fields will be initialized to some sort of null value by
the hash table entry initialization function.
See `ecoff_link_add_externals' for an example of how to check the
`creator' field before saving information (in this case, the ECOFF
external symbol debugging information) in a hash table entry.
File: bfd.info, Node: Adding symbols from an object file, Next: Adding symbols from an archive, Prev: Differing file formats, Up: Adding Symbols to the Hash Table
2.18.2.2 Adding symbols from an object file
...........................................
When the `_bfd_link_add_symbols' routine is passed an object file, it
must add all externally visible symbols in that object file to the hash
table. The actual work of adding the symbol to the hash table is
normally handled by the function `_bfd_generic_link_add_one_symbol'.
The `_bfd_link_add_symbols' routine is responsible for reading all the
symbols from the object file and passing the correct information to
`_bfd_generic_link_add_one_symbol'.
The `_bfd_link_add_symbols' routine should not use
`bfd_canonicalize_symtab' to read the symbols. The point of providing
this routine is to avoid the overhead of converting the symbols into
generic `asymbol' structures.
`_bfd_generic_link_add_one_symbol' handles the details of combining
common symbols, warning about multiple definitions, and so forth. It
takes arguments which describe the symbol to add, notably symbol flags,
a section, and an offset. The symbol flags include such things as
`BSF_WEAK' or `BSF_INDIRECT'. The section is a section in the object
file, or something like `bfd_und_section_ptr' for an undefined symbol
or `bfd_com_section_ptr' for a common symbol.
If the `_bfd_final_link' routine is also going to need to read the
symbol information, the `_bfd_link_add_symbols' routine should save it
somewhere attached to the object file BFD. However, the information
should only be saved if the `keep_memory' field of the `info' argument
is TRUE, so that the `-no-keep-memory' linker switch is effective.
The a.out function which adds symbols from an object file is
`aout_link_add_object_symbols', and most of the interesting work is in
`aout_link_add_symbols'. The latter saves pointers to the hash tables
entries created by `_bfd_generic_link_add_one_symbol' indexed by symbol
number, so that the `_bfd_final_link' routine does not have to call the
hash table lookup routine to locate the entry.
File: bfd.info, Node: Adding symbols from an archive, Prev: Adding symbols from an object file, Up: Adding Symbols to the Hash Table
2.18.2.3 Adding symbols from an archive
.......................................
When the `_bfd_link_add_symbols' routine is passed an archive, it must
look through the symbols defined by the archive and decide which
elements of the archive should be included in the link. For each such
element it must call the `add_archive_element' linker callback, and it
must add the symbols from the object file to the linker hash table.
In most cases the work of looking through the symbols in the archive
should be done by the `_bfd_generic_link_add_archive_symbols' function.
This function builds a hash table from the archive symbol table and
looks through the list of undefined symbols to see which elements
should be included. `_bfd_generic_link_add_archive_symbols' is passed
a function to call to make the final decision about adding an archive
element to the link and to do the actual work of adding the symbols to
the linker hash table.
The function passed to `_bfd_generic_link_add_archive_symbols' must
read the symbols of the archive element and decide whether the archive
element should be included in the link. If the element is to be
included, the `add_archive_element' linker callback routine must be
called with the element as an argument, and the elements symbols must
be added to the linker hash table just as though the element had itself
been passed to the `_bfd_link_add_symbols' function.
When the a.out `_bfd_link_add_symbols' function receives an archive,
it calls `_bfd_generic_link_add_archive_symbols' passing
`aout_link_check_archive_element' as the function argument.
If the latter decides to add the element (an element is only added if
it provides a real, non-common, definition for a previously undefined
or common symbol) it calls the `add_archive_element' callback and then
`aout_link_check_archive_element' calls `aout_link_add_symbols' to
actually add the symbols to the linker hash table.
The ECOFF back end is unusual in that it does not normally call
`_bfd_generic_link_add_archive_symbols', because ECOFF archives already
contain a hash table of symbols. The ECOFF back end searches the
archive itself to avoid the overhead of creating a new hash table.
File: bfd.info, Node: Performing the Final Link, Prev: Adding Symbols to the Hash Table, Up: Linker Functions
2.18.3 Performing the final link
--------------------------------
When all the input files have been processed, the linker calls the
`_bfd_final_link' entry point of the output BFD. This routine is
responsible for producing the final output file, which has several
aspects. It must relocate the contents of the input sections and copy
the data into the output sections. It must build an output symbol
table including any local symbols from the input files and the global
symbols from the hash table. When producing relocatable output, it must
modify the input relocs and write them into the output file. There may
also be object format dependent work to be done.
The linker will also call the `write_object_contents' entry point
when the BFD is closed. The two entry points must work together in
order to produce the correct output file.
The details of how this works are inevitably dependent upon the
specific object file format. The a.out `_bfd_final_link' routine is
`NAME(aout,final_link)'.
* Menu:
* Information provided by the linker::
* Relocating the section contents::
* Writing the symbol table::
File: bfd.info, Node: Information provided by the linker, Next: Relocating the section contents, Prev: Performing the Final Link, Up: Performing the Final Link
2.18.3.1 Information provided by the linker
...........................................
Before the linker calls the `_bfd_final_link' entry point, it sets up
some data structures for the function to use.
The `input_bfds' field of the `bfd_link_info' structure will point
to a list of all the input files included in the link. These files are
linked through the `link_next' field of the `bfd' structure.
Each section in the output file will have a list of `link_order'
structures attached to the `link_order_head' field (the `link_order'
structure is defined in `bfdlink.h'). These structures describe how to
create the contents of the output section in terms of the contents of
various input sections, fill constants, and, eventually, other types of
information. They also describe relocs that must be created by the BFD
backend, but do not correspond to any input file; this is used to
support -Ur, which builds constructors while generating a relocatable
object file.
File: bfd.info, Node: Relocating the section contents, Next: Writing the symbol table, Prev: Information provided by the linker, Up: Performing the Final Link
2.18.3.2 Relocating the section contents
........................................
The `_bfd_final_link' function should look through the `link_order'
structures attached to each section of the output file. Each
`link_order' structure should either be handled specially, or it should
be passed to the function `_bfd_default_link_order' which will do the
right thing (`_bfd_default_link_order' is defined in `linker.c').
For efficiency, a `link_order' of type `bfd_indirect_link_order'
whose associated section belongs to a BFD of the same format as the
output BFD must be handled specially. This type of `link_order'
describes part of an output section in terms of a section belonging to
one of the input files. The `_bfd_final_link' function should read the
contents of the section and any associated relocs, apply the relocs to
the section contents, and write out the modified section contents. If
performing a relocatable link, the relocs themselves must also be
modified and written out.
The functions `_bfd_relocate_contents' and
`_bfd_final_link_relocate' provide some general support for performing
the actual relocations, notably overflow checking. Their arguments
include information about the symbol the relocation is against and a
`reloc_howto_type' argument which describes the relocation to perform.
These functions are defined in `reloc.c'.
The a.out function which handles reading, relocating, and writing
section contents is `aout_link_input_section'. The actual relocation
is done in `aout_link_input_section_std' and
`aout_link_input_section_ext'.
File: bfd.info, Node: Writing the symbol table, Prev: Relocating the section contents, Up: Performing the Final Link
2.18.3.3 Writing the symbol table
.................................
The `_bfd_final_link' function must gather all the symbols in the input
files and write them out. It must also write out all the symbols in
the global hash table. This must be controlled by the `strip' and
`discard' fields of the `bfd_link_info' structure.
The local symbols of the input files will not have been entered into
the linker hash table. The `_bfd_final_link' routine must consider
each input file and include the symbols in the output file. It may be
convenient to do this when looking through the `link_order' structures,
or it may be done by stepping through the `input_bfds' list.
The `_bfd_final_link' routine must also traverse the global hash
table to gather all the externally visible symbols. It is possible
that most of the externally visible symbols may be written out when
considering the symbols of each input file, but it is still necessary
to traverse the hash table since the linker script may have defined
some symbols that are not in any of the input files.
The `strip' field of the `bfd_link_info' structure controls which
symbols are written out. The possible values are listed in
`bfdlink.h'. If the value is `strip_some', then the `keep_hash' field
of the `bfd_link_info' structure is a hash table of symbols to keep;
each symbol should be looked up in this hash table, and only symbols
which are present should be included in the output file.
If the `strip' field of the `bfd_link_info' structure permits local
symbols to be written out, the `discard' field is used to further
controls which local symbols are included in the output file. If the
value is `discard_l', then all local symbols which begin with a certain
prefix are discarded; this is controlled by the
`bfd_is_local_label_name' entry point.
The a.out backend handles symbols by calling
`aout_link_write_symbols' on each input BFD and then traversing the
global hash table with the function `aout_link_write_other_symbol'. It
builds a string table while writing out the symbols, which is written
to the output file at the end of `NAME(aout,final_link)'.
File: bfd.info, Node: Hash Tables, Prev: Linker Functions, Up: BFD front end
2.19 Hash Tables
================
BFD provides a simple set of hash table functions. Routines are
provided to initialize a hash table, to free a hash table, to look up a
string in a hash table and optionally create an entry for it, and to
traverse a hash table. There is currently no routine to delete an
string from a hash table.
The basic hash table does not permit any data to be stored with a
string. However, a hash table is designed to present a base class from
which other types of hash tables may be derived. These derived types
may store additional information with the string. Hash tables were
implemented in this way, rather than simply providing a data pointer in
a hash table entry, because they were designed for use by the linker
back ends. The linker may create thousands of hash table entries, and
the overhead of allocating private data and storing and following
pointers becomes noticeable.
The basic hash table code is in `hash.c'.
* Menu:
* Creating and Freeing a Hash Table::
* Looking Up or Entering a String::
* Traversing a Hash Table::
* Deriving a New Hash Table Type::
File: bfd.info, Node: Creating and Freeing a Hash Table, Next: Looking Up or Entering a String, Prev: Hash Tables, Up: Hash Tables
2.19.1 Creating and freeing a hash table
----------------------------------------
To create a hash table, create an instance of a `struct bfd_hash_table'
(defined in `bfd.h') and call `bfd_hash_table_init' (if you know
approximately how many entries you will need, the function
`bfd_hash_table_init_n', which takes a SIZE argument, may be used).
`bfd_hash_table_init' returns `FALSE' if some sort of error occurs.
The function `bfd_hash_table_init' take as an argument a function to
use to create new entries. For a basic hash table, use the function
`bfd_hash_newfunc'. *Note Deriving a New Hash Table Type::, for why
you would want to use a different value for this argument.
`bfd_hash_table_init' will create an objalloc which will be used to
allocate new entries. You may allocate memory on this objalloc using
`bfd_hash_allocate'.
Use `bfd_hash_table_free' to free up all the memory that has been
allocated for a hash table. This will not free up the `struct
bfd_hash_table' itself, which you must provide.
Use `bfd_hash_set_default_size' to set the default size of hash
table to use.
File: bfd.info, Node: Looking Up or Entering a String, Next: Traversing a Hash Table, Prev: Creating and Freeing a Hash Table, Up: Hash Tables
2.19.2 Looking up or entering a string
--------------------------------------
The function `bfd_hash_lookup' is used both to look up a string in the
hash table and to create a new entry.
If the CREATE argument is `FALSE', `bfd_hash_lookup' will look up a
string. If the string is found, it will returns a pointer to a `struct
bfd_hash_entry'. If the string is not found in the table
`bfd_hash_lookup' will return `NULL'. You should not modify any of the
fields in the returns `struct bfd_hash_entry'.
If the CREATE argument is `TRUE', the string will be entered into
the hash table if it is not already there. Either way a pointer to a
`struct bfd_hash_entry' will be returned, either to the existing
structure or to a newly created one. In this case, a `NULL' return
means that an error occurred.
If the CREATE argument is `TRUE', and a new entry is created, the
COPY argument is used to decide whether to copy the string onto the
hash table objalloc or not. If COPY is passed as `FALSE', you must be
careful not to deallocate or modify the string as long as the hash table
exists.
File: bfd.info, Node: Traversing a Hash Table, Next: Deriving a New Hash Table Type, Prev: Looking Up or Entering a String, Up: Hash Tables
2.19.3 Traversing a hash table
------------------------------
The function `bfd_hash_traverse' may be used to traverse a hash table,
calling a function on each element. The traversal is done in a random
order.
`bfd_hash_traverse' takes as arguments a function and a generic
`void *' pointer. The function is called with a hash table entry (a
`struct bfd_hash_entry *') and the generic pointer passed to
`bfd_hash_traverse'. The function must return a `boolean' value, which
indicates whether to continue traversing the hash table. If the
function returns `FALSE', `bfd_hash_traverse' will stop the traversal
and return immediately.
File: bfd.info, Node: Deriving a New Hash Table Type, Prev: Traversing a Hash Table, Up: Hash Tables
2.19.4 Deriving a new hash table type
-------------------------------------
Many uses of hash tables want to store additional information which
each entry in the hash table. Some also find it convenient to store
additional information with the hash table itself. This may be done
using a derived hash table.
Since C is not an object oriented language, creating a derived hash
table requires sticking together some boilerplate routines with a few
differences specific to the type of hash table you want to create.
An example of a derived hash table is the linker hash table. The
structures for this are defined in `bfdlink.h'. The functions are in
`linker.c'.
You may also derive a hash table from an already derived hash table.
For example, the a.out linker backend code uses a hash table derived
from the linker hash table.
* Menu:
* Define the Derived Structures::
* Write the Derived Creation Routine::
* Write Other Derived Routines::
File: bfd.info, Node: Define the Derived Structures, Next: Write the Derived Creation Routine, Prev: Deriving a New Hash Table Type, Up: Deriving a New Hash Table Type
2.19.4.1 Define the derived structures
......................................
You must define a structure for an entry in the hash table, and a
structure for the hash table itself.
The first field in the structure for an entry in the hash table must
be of the type used for an entry in the hash table you are deriving
from. If you are deriving from a basic hash table this is `struct
bfd_hash_entry', which is defined in `bfd.h'. The first field in the
structure for the hash table itself must be of the type of the hash
table you are deriving from itself. If you are deriving from a basic
hash table, this is `struct bfd_hash_table'.
For example, the linker hash table defines `struct
bfd_link_hash_entry' (in `bfdlink.h'). The first field, `root', is of
type `struct bfd_hash_entry'. Similarly, the first field in `struct
bfd_link_hash_table', `table', is of type `struct bfd_hash_table'.
File: bfd.info, Node: Write the Derived Creation Routine, Next: Write Other Derived Routines, Prev: Define the Derived Structures, Up: Deriving a New Hash Table Type
2.19.4.2 Write the derived creation routine
...........................................
You must write a routine which will create and initialize an entry in
the hash table. This routine is passed as the function argument to
`bfd_hash_table_init'.
In order to permit other hash tables to be derived from the hash
table you are creating, this routine must be written in a standard way.
The first argument to the creation routine is a pointer to a hash
table entry. This may be `NULL', in which case the routine should
allocate the right amount of space. Otherwise the space has already
been allocated by a hash table type derived from this one.
After allocating space, the creation routine must call the creation
routine of the hash table type it is derived from, passing in a pointer
to the space it just allocated. This will initialize any fields used
by the base hash table.
Finally the creation routine must initialize any local fields for
the new hash table type.
Here is a boilerplate example of a creation routine. FUNCTION_NAME
is the name of the routine. ENTRY_TYPE is the type of an entry in the
hash table you are creating. BASE_NEWFUNC is the name of the creation
routine of the hash table type your hash table is derived from.
struct bfd_hash_entry *
FUNCTION_NAME (entry, table, string)
struct bfd_hash_entry *entry;
struct bfd_hash_table *table;
const char *string;
{
struct ENTRY_TYPE *ret = (ENTRY_TYPE *) entry;
/* Allocate the structure if it has not already been allocated by a
derived class. */
if (ret == (ENTRY_TYPE *) NULL)
{
ret = ((ENTRY_TYPE *)
bfd_hash_allocate (table, sizeof (ENTRY_TYPE)));
if (ret == (ENTRY_TYPE *) NULL)
return NULL;
}
/* Call the allocation method of the base class. */
